DIRSCAN by Donald L. Wallace Copyright 1997 by Donald L. Wallace. OVERVIEW DIRSCAN provides a simple, component-based way for your Delphi program to search through a directory tree in order to look for file(s) which conform to a file name wilcard specification and a possible test of contents. DIRSCAN is a non - visual VCL component that is source code compatible with both Delphi 1 and Delphi 2. DIRSCAN encapsulates the Windows API functions FindFirst and FindNext to recursively scan subdirectories. I offer DIRSCAN freely to the Delphi programming community. Use DIRSCAN in any way you like, including educational, commercial or personal use. Frankly, I think DIRSCAN has greater value as self-promotion and as a goodwill token than as a money making product. Just don't take credit for writing it, and include the copyright notice in any source code into which you embed DIRSCAN! USING THE TEST PROGRAM Unzip the ZIP file to a directory. Install the file TDIRSCAN.PAS to your component palette. Refer to Delphi product documentation for assistance. Load the project file DIRSCAN.DPR. Run the project. The program allows you to exercise the directory scan component. Enter a path, filename to search for, and press 'Scan' to start a search. TECHNICAL REFERENCE Source for component: DIRSCAN.PAS. Component Name: TDirectoryScan Properties Directory : String You set this property to specify the top most directory path that is to be scanned. 'Directory' should be specified in the standard drive letter - colon - backslash - path format. In Win32, do use double quotes to surround long path specifications that contain spaces when creating a value to place into 'Directory'. It is recommended to use a path starting with a relative specification (IE, a path such as ..\Mydir) FileName : String You set this property in order to specify the wildcard for files to be matched. If not set, the default used by the component is *.* (all files.) Subdirectories : Boolean You set this property to control whether the control will scan subdirectories. Default is TRUE. CurDirectory : String Read-only. This property will contain the current directory path being scanned by the component. This property is useful only within the OnProgress event handler. TotalCount : Integer Read-only. This property will contain the current number of files which have been matched by the component. This property is useful only within the OnProgress event handler. Events procedure OnProgress(Sender : TObject;path : String); Purpose: OnProgress is called every time the component scans a new directory (when the component first gathers directory paths) and every time the component scans a new file. OnProgress can update a user interface with current scan information. See CurDirectory and TotalCount properties. Procedure OnVerifyFile(Sender : TObject;path : String; stream : TFileStream;TimeStamp : TDateTime; var PassFlag : Boolean); Purpose: OnVerifyFile is called every time the component locates a file which matches the 'FileName' property. The purpose of OnVerifyFile is to allow your code to determine if a file has a date stamp or contents which make it eligible to be included as a 'found' file. 'path' is the fully qualified file name; 'stream' is opened already in read mode, sharing enabled, for the file passed in 'path', with the file pointer at the start of the file. 'TimeStamp' is the last update time of the file. 'PassFlag' should be set TRUE by your code on exit if the file is to be used, or FALSE if the file is to be ignored. If FALSE is returned, OnProcessFile will not be called by the component for the file. (NOTE: If OnVerifyFile is set to an event handler, the scanning process will execute much more quickly than if OnVerifyFile is set. The reason for this speed difference is that every scanned file has a file handle opened for it per the 'stream' argument when an event handler is set for this event type. Also, every file that matches 'FileName' will be accepted if there is no OnVerifyFile handler set.) procedure OnDirList(Sender : TObject;paths : TStrings); Purpose: OnDirList is called when the component has gathered all sub-directories of the 'Directory' path. Every entry in 'paths' is a subdirectory of 'Directory' which will be scanned for instances of 'FileName' after OnDirList returns. Subdirectories are listed in 'paths' immediately following their parent directories. Your code may perform any valid manipulation of 'paths', including insertion or deletion of entries, or copying of the contents of 'paths' to other storage. procedure OnProcessDirectory(Sender : TObject;path : String); Purpose: OnProcessDirectory is called every time the component scans a new directory or subdirectory which contains a matching file. 'path' will contain the directory name. OnProcessDirectory will be called just once per each directory that contains a matching file. procedure OnProcessFile(Sender : TObject;path : String); Purpose: OnProcessFile is called every time the component locates a matching file. 'Matching' is defined as matching the property value last set for 'FileName' plus being accepted by OnVerifyFile if OnVerifyFile is set. 'path' will contain the file name specified as a full path specification. Methods Function Execute : Boolean; Purpose: The application calls 'Execute' in order to perform a scan for files which match the specifications passed in properties 'Directory' and 'FileName', and which pass the optional test which may be performed by the event handler 'OnVerifyFile'. 'Execute' returns TRUE if at least one matching file was located, FALSE if none. 'Execute' also returns immediately with the value FALSE if 'Execute' is called re-entrantly (that is, while the same component is already running the 'Execute' method). Procedure Cancel; Purpose: The application calls 'Cancel' in order to force the currently-executing method 'Execute' to return immediately. Typically a call to method 'Cancel' would be invoked by a button press. If 'Cancel' is called when 'Execute' is not running for the component, then nothing will happen. DELPHI 1 / DELPHI 2 DEPENDENCIES There are the following areas of difference between Delphi 1 and Delphi 2 usage. - If built with Delphi 1, all file names and path names collected will be in the 8.3 character "classic DOS" format, even if the program is run in a Win32 system supporting long file names. Long path names will be translated into 8.3 character equivalents. In Delphi 2, all file names and path names that are collected. may potentially be long file names with embedded space characters. - There is no 'Trim' function in Delphi 1, so the function is provided for Delphi 1 as conditionally compiled code. - Delphi 1 strings may only be 255 characters or less. There is one conditionally compiled test to guard against excessively long file names. I have not tested the program exhaustively against long path name problems. ABOUT THE AUTHOR I am an independent consultant available for software development projects and technological mentoring in Delphi, VB, and C++. Need a VCL developed? I can do this sort of work for your organization. Based in Ohio, available for consultation. Please email directly to Compuserve 71247,3221, or donaldw@your-net.com for details.